home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib / tk / FileHndlr.man < prev    next >
Encoding:
Text File  |  1992-08-24  |  7.2 KB  |  275 lines
  1. '\"
  2. '\" Copyright 1990 Regents of the University of California
  3. '\" Permission to use, copy, modify, and distribute this
  4. '\" documentation for any purpose and without fee is hereby
  5. '\" granted, provided that this notice appears in all copies.
  6. '\" The University of California makes no representations about
  7. '\" the suitability of this material for any purpose.  It is
  8. '\" provided "as is" without express or implied warranty.
  9. '\" 
  10. '\" $Header: /user6/ouster/wish/man/RCS/FileHndlr.man,v 1.5 91/12/06 10:39:01 ouster Exp $ SPRITE (Berkeley)
  11. '\" 
  12. .\" The definitions below are for supplemental macros used in Sprite
  13. .\" manual entries.
  14. .\"
  15. .\" .HS name section [date [version]]
  16. .\"    Replacement for .TH in other man pages.  See below for valid
  17. .\"    section names.
  18. .\"
  19. .\" .AP type name in/out [indent]
  20. .\"    Start paragraph describing an argument to a library procedure.
  21. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  22. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  23. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  24. .\"    needed;  use .AS below instead)
  25. .\"
  26. .\" .AS [type [name]]
  27. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  28. .\"    name are examples of largest possible arguments that will be passed
  29. .\"    to .AP later.  If args are omitted, default tab stops are used.
  30. .\"
  31. .\" .BS
  32. .\"    Start box enclosure.  From here until next .BE, everything will be
  33. .\"    enclosed in one large box.
  34. .\"
  35. .\" .BE
  36. .\"    End of box enclosure.
  37. .\"
  38. .\" .VS
  39. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  40. .\"    of man pages.
  41. .\"
  42. .\" .VE
  43. .\"    End of vertical sidebar.
  44. .\"
  45. .\" .DS
  46. .\"    Begin an indented unfilled display.
  47. .\"
  48. .\" .DE
  49. .\"    End of indented unfilled display.
  50. .\"
  51. '\"    # Heading for Sprite man pages
  52. .de HS
  53. .if '\\$2'cmds'       .TH \\$1 1 \\$3 \\$4
  54. .if '\\$2'lib'        .TH \\$1 3 \\$3 \\$4
  55. .if '\\$2'tcl'        .TH \\$1 3 \\$3 \\$4
  56. .if '\\$2'tk'         .TH \\$1 3 \\$3 \\$4
  57. .if t .wh -1.3i ^B
  58. .nr ^l \\n(.l
  59. .ad b
  60. ..
  61. '\"    # Start an argument description
  62. .de AP
  63. .ie !"\\$4"" .TP \\$4
  64. .el \{\
  65. .   ie !"\\$2"" .TP \\n()Cu
  66. .   el          .TP 15
  67. .\}
  68. .ie !"\\$3"" \{\
  69. .ta \\n()Au \\n()Bu
  70. \&\\$1    \\fI\\$2\\fP    (\\$3)
  71. .\".b
  72. .\}
  73. .el \{\
  74. .br
  75. .ie !"\\$2"" \{\
  76. \&\\$1    \\fI\\$2\\fP
  77. .\}
  78. .el \{\
  79. \&\\fI\\$1\\fP
  80. .\}
  81. .\}
  82. ..
  83. '\"    # define tabbing values for .AP
  84. .de AS
  85. .nr )A 10n
  86. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  87. .nr )B \\n()Au+15n
  88. .\"
  89. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  90. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  91. ..
  92. '\"    # BS - start boxed text
  93. '\"    # ^y = starting y location
  94. '\"    # ^b = 1
  95. .de BS
  96. .br
  97. .mk ^y
  98. .nr ^b 1u
  99. .if n .nf
  100. .if n .ti 0
  101. .if n \l'\\n(.lu\(ul'
  102. .if n .fi
  103. ..
  104. '\"    # BE - end boxed text (draw box now)
  105. .de BE
  106. .nf
  107. .ti 0
  108. .mk ^t
  109. .ie n \l'\\n(^lu\(ul'
  110. .el \{\
  111. .\"    Draw four-sided box normally, but don't draw top of
  112. .\"    box if the box started on an earlier page.
  113. .ie !\\n(^b-1 \{\
  114. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  115. .\}
  116. .el \}\
  117. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  118. .\}
  119. .\}
  120. .fi
  121. .br
  122. .nr ^b 0
  123. ..
  124. '\"    # VS - start vertical sidebar
  125. '\"    # ^Y = starting y location
  126. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  127. .de VS
  128. .mk ^Y
  129. .ie n 'mc \s12\(br\s0
  130. .el .nr ^v 1u
  131. ..
  132. '\"    # VE - end of vertical sidebar
  133. .de VE
  134. .ie n 'mc
  135. .el \{\
  136. .ev 2
  137. .nf
  138. .ti 0
  139. .mk ^t
  140. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  141. .sp -1
  142. .fi
  143. .ev
  144. .\}
  145. .nr ^v 0
  146. ..
  147. '\"    # Special macro to handle page bottom:  finish off current
  148. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  149. '\"    # page bottom macro.
  150. .de ^B
  151. .ev 2
  152. 'ti 0
  153. 'nf
  154. .mk ^t
  155. .if \\n(^b \{\
  156. .\"    Draw three-sided box if this is the box's first page,
  157. .\"    draw two sides but no top otherwise.
  158. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  159. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  160. .\}
  161. .if \\n(^v \{\
  162. .nr ^x \\n(^tu+1v-\\n(^Yu
  163. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  164. .\}
  165. .bp
  166. 'fi
  167. .ev
  168. .if \\n(^b \{\
  169. .mk ^y
  170. .nr ^b 2
  171. .\}
  172. .if \\n(^v \{\
  173. .mk ^Y
  174. .\}
  175. ..
  176. '\"    # DS - begin display
  177. .de DS
  178. .RS
  179. .nf
  180. .sp
  181. ..
  182. '\"    # DE - end display
  183. .de DE
  184. .fi
  185. .RE
  186. .sp .5
  187. ..
  188. .HS Tk_CreateFileHandler tk
  189. .BS
  190. .SH NAME
  191. Tk_CreateFileHandler, Tk_DeleteFileHandler \- associate procedure callback with a file or device
  192. .SH SYNOPSIS
  193. .nf
  194. \fB#include <tk.h>\fR
  195. .sp
  196. \fBTk_CreateFileHandler\fR(\fIid, mask, proc, clientData\fR)
  197. .sp
  198. \fBTk_DeleteFileHandler\fR(\fIid\fR)
  199. .SH ARGUMENTS
  200. .AS Tk_FileProc clientData
  201. .AP int id in
  202. Integer identifier for an open file or device (such as returned by
  203. \fBopen\fR system call).
  204. .AP int mask in
  205. Conditions under which \fIproc\fR should be called:
  206. OR-ed combination of \fBTK_READABLE\fR, \fBTK_WRITABLE\fR,
  207. and \fBTK_EXCEPTION\fR.
  208. .AP Tk_FileProc *proc in
  209. Procedure to invoke whenever the file or device indicated
  210. by \fIid\fR meets the conditions specified by \fImask\fR.
  211. .AP ClientData clientData in
  212. Arbitrary one-word value to pass to \fIproc\fR.
  213. .BE
  214.  
  215. .SH DESCRIPTION
  216. .PP
  217. \fBTk_CreateFileHandler\fR arranges for \fIproc\fR to be
  218. invoked in the future whenever I/O becomes possible on a file
  219. or an exceptional condition exists for the file.  The file
  220. is indicated by \fIid\fR, and the conditions of interest
  221. are indicated by \fImask\fR.  For example, if \fImask\fR
  222. is \fBTK_READABLE\fR, then \fIproc\fR will be called when
  223. the file is readable.
  224. The callback to \fIproc\fR is made by \fBTk_DoOneEvent\fR, so
  225. \fBTk_CreateFileHandler\fR is only useful
  226. in programs that dispatch events
  227. through \fBTk_DoOneEvent\fR or through other Tk procedures that
  228. call \fBTk_DoOneEvent\fR, such as \fBTk_MainLoop\fR.
  229. .PP
  230. \fIProc\fP should have arguments and result that match the
  231. type \fBTk_FileProc\fR:
  232. .nf
  233. .RS
  234. typedef void Tk_FileProc(
  235. .RS
  236. ClientData \fIclientData\fR,
  237. int \fImask\fR);
  238. .RE
  239. .RE
  240. .fi
  241. The \fIclientData\fP parameter to \fIproc\fR is a copy
  242. of the \fIclientData\fP
  243. argument given to \fBTcl_CreateFileHandler\fR when the callback
  244. was created.  Typically, \fIclientData\fR points to a data
  245. structure containing application-specific information about
  246. the file.  \fIMask\fR is an integer mask indicating which
  247. of the requested conditions actually exists for the file;  it
  248. will contain a subset of the bits in the \fImask\fR argument
  249. to \fBTcl_CreateFileHandler\fR.
  250. .PP
  251. There may exist only one handler for a given file at a given
  252. time.  If \fBTk_CreateEventHandler\fR is called when a handler
  253. already exists for \fIid\fR, then the \fImask\fR, \fIproc\fR,
  254. and \fIclientData\fR for the new call to
  255. \fBTk_CreateEventHandler\fR replace the information that was
  256. previously recorded.
  257. .PP
  258. \fBTk_DeleteFileHandler\fR may be called to delete the
  259. file handler for \fIid\fR;  if no handler exists for the
  260. file given by \fIid\fR then the procedure has no effect.
  261. .PP
  262. The purpose of file handlers is to enable an application to
  263. respond to X events and other events while waiting for files
  264. to become ready for I/O.  For this to work correctly, the
  265. application must use non-blocking I/O operations on the
  266. files for which handlers are declared.  Otherwise the application
  267. may be put to sleep if it specifies too large an input or
  268. output buffer; while waiting for the I/O to complete the
  269. application won't be able to service other events.  In BSD-based
  270. UNIX systems, non-blocking I/O can be specified for a file using
  271. the \fBfcntl\fR kernel call with the \fBFNDELAY\fR flag.
  272.  
  273. .SH KEYWORDS
  274. callback, file, handler
  275.